Cream of the Crop 25/Cream of the Crop 25.iso/disk/ncom23.zip/WINDOWS/MLISTBOX.TXT

Text File | 1992-10-26 | 12KB | 385 lines

                                MLISTBOX.VBX

MLISTBOX.VBX is a custom control for Microsoft Visual Basic which provides
support for extended- and multiple-selection listboxes as well as the
standard single-selection listboxes that are built into Visual Basic.

This product is (pseudo) shareware.  Information on distribution rights is
provided at the end of this file.

I welcome any comments, criticisms, suggestions, etc.  I can be reached
via e-mail at:

        [e-mail]

(I would also be interested to know where you obtained your copy of
MLISTBOX.)

Mike Warning
Oct 25, 1992


                          HOW TO USE CUSTOM CONTROLS

For those of you unfamiliar with using custom controls in Visual Basic, it is
really easy.  First, copy the file ending with .VBX to your windows
directory.  The start up Visual Basic and select 'Add File...' from the
'File' menu.  Locate the custom control file (.VBX file) that you wish to
use and select it, then click 'OK'.  The icon representing the custom control
should appear in the toolbox window and may be used just like any of the
standard controls.  If you then save your project, the custom control will
be reloaded automatically the next time you open your project.


                                  REFERENCE

Since I have made every effort to preserve the functionality of the original
single-selection listbox in my version, I will only address those properties
that are new or that I have expanded.  For information on the standard
properties not covered here, refer to the Visual Basic documentation.

A number in parenthesis after the name of the property specifies what version
of MListbox first supported it.

Note that when I refer to 'multiple-selection listboxes' below, I really
mean 'multiple- or extended-selection listboxes'.


AutoRedraw - (1.1)
    Controls how the listbox is updated when an item is added or removed.
    The default is TRUE.

    If AutoRedraw is TRUE, the listbox acts just like the standard single-
    selection VB listbox - the entire box is redrawn at the end of an
    event procedure (or during a DoEvents() call) if an item has been
    added or removed.

    If AutoRedraw is FALSE, then the listbox will not get redrawn until
    you change it back to TRUE.  This is useful when you need to add a
    a lot of items in a loop with a DoEvents() call and want to avoid
    flashing.

    Example:
        ...
        mlistbox1.AutoRedraw = FALSE
        For i = 1 to 50
            mlistbox1.AddItem Format$(i)
            e = DoEvents()
        Next i
        mlistbox1.AutoRedraw = TRUE
        ...


Empty -
    When reading this property, a TRUE will be returned if the listbox is
    empty, otherwise a FALSE will be returned.  Writing any value to this
    property will force the listbox to reset, discarding any items that
    it contains.

    Example:
        ...
        mlistbox1.Empty = TRUE          ' Clear listbox
        ...


FindString -
    This property is used to find strings in a listbox.  When this property
    is set, the 'FindIndex' property may then be checked to find the index
    of the first string in the listbox matching the FindString.  After
    a string is found, this property will reset to the value of the string
    in the listbox.

    FindString will reset to null ("") if there is no string in the listbox
    matching the value that you gave it.

    Example:
        ...
        mlistbox1.FindString = "J"      ' Find an item beginning with "J"
        If mlistbox1.FindString = "John" Then
        ...

    See Also:
        FindIndex


FindIndex -
    This property hold the index of the string found using FindString.  It
    will be set to -1 if there is no matching string.

    Example:
        ...
        mlistbox1.FindString = "J"      ' Find an item beginning with "J"
        If mlistbox1.FindIndex = -1 then        ' There isn't any
        ...

    See Also:
        FindString


hWnd -
    This property is the window handle associated with the listbox and is
    exactly like the 'hWnd' property that forms have.  This function is
    useful when a window handle must be passed to a Windows API function
    or other DLL function.

    Example:
        ...
        word = GetWindowWord(mlistbox1.hWnd, GWW_ID)
        ...


ItemData -
    This property associates a long-integer value with an item in the
    listbox.  For example, if you have a listbox containing names, you could
    put there ages (or whatever) in the ItemData for a particular item.

    This property is similar to the standard 'Tag' property, except that
    it is numeric, and each item in the control can have it's own data.

    Example:
        ...
        mlistbox.ItemData(3) = 34
        ...


ListIndex -
    For single-selection listboxes, ListIndex returns the index of the
    currently selected item.  For multiple-selection listboxes, ListIndex
    returns the index of the last item that the user clicked on, the
    'Selected' property may then be used to find out if that item is
    currently selected or not.

    If there is no current selection, single-selection listboxes will
    return -1.  If no selection has ever been made, multiple-selection
    listboxes will return 0.

    NOTE:  The Windows SDK says that this should not work for multiple-
    selection listboxes; however, it seems to work fine under Windows 3.0
    and 3.1.  Therefore, I cannot guarantee that this property will work
    correctly for multiple-selection listboxes under future versions of
    Windows.

    Example:
        ...
        If mlistbox1.ListIndex = -1 then
        ...


SelCount -
    Returns the number of selected items in the listbox.

    Example:
        ...
        For i=1 to mlistbox1.SelCount - 1
        ...

    See Also:
        SelCount, Selected


Selected -
    When read, this property returns a TRUE if the item is selected,
    otherwise a FALSE is returned.

    When writing, this property may be used to select (or deselect) an
    item in the listbox.  For single-selection listboxes, if another item
    is currently selected, the selection will change to a new item.  Also,
    an item cannot be deselected in a single-selection listbox using this
    property (use ListIndex instead).

    Example:
        ...
        for i=0 to mlistbox1.SelCount - 1
            mlistbox1.Selected =  TRUE          ' select every item
        next
        ...

    See Also:
        SelCount, SelList, ListIndex


SelList -
    The property is an array that contains the indexes of the currently
    selected items in the listbox.  The first selected item is SelList(0),
    etc.

    Example:
        ...
        For i=0 to mlistbox1.SelCount - 1
            if mlistbox1.list(mlistbox1.SelList(i)) = "John" then
        ...

    See Also:
        SelCount, Selected


Style -
    This property sets the style of the listbox (single-, extended-, or
    multiple-selection).

    Style = 0: single-selection.  This type of listbox may only have one
               item selected at a time.
    Style = 1: extended-selection.  This type of listbox may have more than
               one item selected.  The user must hold down the 'CTRL' or
               'SHIFT' keys while clicking the mouse to select more than
               one item
    Style = 2: multiple-selection.  This type of listbox may have more than
               one item selected.  The user does not need to hold down any
               keys while selecting items.

    You should probably set the Style property at design time.  While you
    may change the Style at run-time, doing so clears out the contents of
    the listbox.

    Example:
        CONST EXTENDED_SELECTION = 1
        ...
        mlistbox1.Style = EXTENDED_SELECTION
        ...


Tabs - (1.1)
    A string that contains the location of tabs within the listbox.

    If you do not specify any tab locations (i.e. Tabs = ""), Windows
    will automatically set a tab every 32 dialog units.

    If you specify only one tab, the listbox will have a tab at every
    'n' dialog units.  For example:  Tabs = "10" will set a tab every
    10 dialog units.

    For more than one tab, There will be a tab set at just the positions
    that you specified, and then every 32 positions from then on.  For
    example:  Tabs = "10 20" will set a tab at 10, then at 20, then at
    32, 64, etc.

    Example:
        ...
        t$ = Chr$(9)            ' Chr$(9) is a tab character
        mlistbox1.additem "John" + t$ + "Doe"
        ...


Text -
    For single-selection listboxes, Text returns the currently selected item
    in the listbox.  For multiple-selection listboxes the item that was most
    recently clicked is returned, you can then use the 'Selected', and
    'ListIndex' properties to determine if the item is selected or not.

    NOTE:  The Windows SDK says that this should not work for multiple-
    selection listboxes; however, it seems to work fine under Windows 3.0.
    Therefore, I cannot guarantee that this property will work correctly
    for multiple-selection listboxes under future versions of Windows.

    Example:
        ...
        if (mlistbox1.text = "John") then
        ...

    See Also:
        ListIndex, Selected


TopIndex -
    Sets the index of the item that is at the top of the listbox.   If you
    try to set the top index to an item number less than 0, the listbox
    will start from item 0.  If you try to use an index that is to high
    the listbox will not change.

    Example:
        ...
        mlistbox1.TopIndex = mlistbox1.TopIndex + 1     ' Scroll by one line
        ...


Version - (1.1)
    Version is a read-only property that returns the version of the MListbox
    custom control file.

    Any attempt to write to this property is simply ignored.

    NOTE: This property was not supported in version 1.0 of MListbox.

    Example:
        ...
        If mlistbox1.Version = 1.1 then
        ...

                                PROPERTIES

This is a comprehensive list of all properties supported by the control:

    CtlName     Index       BackColor   ForeColor   Left
    Top         Width       Height      MousePointer
    TabIndex    TabStop     DragIcon    DragMode    Enabled
    Parent      Tag         Visible     FontName    FontBold
    FontItalic  FontStrikethru          FontSize    FontUnder
    ListCount   SelCount    ListIndex   TopIndex    List
    Empty       SelList     Style       Text        Sorted
    Selected    FindString  FindIndex   ItemData    hWnd
    AutoRedraw  Tabs        Version

                                  EVENTS

    Click       DblClick    DragDrop    DragOver    GotFocus
    KeyDown     KeyPress    KeyUp       LostFocus   MouseDown
    MouseMove   MouseUp

                                 METHODS

    AddItem     RemoveItem  Refresh     Load        Unload


                             VERSION HISTORY

1.1   - Oct 25, 1992

        Fixed a bug relating to the Windows message WM_SETREDRAW.
        Fixed a bug relating to the background color while in design mode.

        Added the AutoRedraw, Tabs, and Version properties.

        Verified compatibility with Windows 3.1
        Converted from MS QC/Win 1.0 to MS C 7.00

1.0   - February 16, 1992

        Initial release


                            DISTRIBUTION RIGHTS

You are free to distribute this product separately from a product of your
own, as long as you distribute both this file, and the custom control file
(MLISTBOX.VBX).

If you wish to use this product in one of your own products, your rights
depend on what sort of product it is:

Public Domain:  i.e. not for profit, you ask no monetary fee for someone
to use your product.  In this case, you are free to distribute this control
as much as you wish.

Shareware:  i.e. requesting that the user send you some money if they
like/use your product.  In this case, please send me a postcard of your
home town or some feature thereabouts.

Commercial:  i.e. for profit.  In this case, please contact me (see below),
and we can arrange some mutually beneficial agreement.


I may be reached either through e-mail at:

    [e-mail]

or through regular mail at:

    Mike Warning
    6015 202nd St. S.W. #14
    Lynnwood, WA 98036

If you wish a prompt reply, please use e-mail.  I do not actually live at
the mailing address above, and it may take weeks/months to get anything to
me that is sent there.